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PREFACE 


This manual describes the features and operation of FILCOM, a system 
program for DOS /BATCH, The reader should be familiar with the 
DOS/BATCH Monitor as described in the DOS/BATCH Monitor Programmer's 
Manual . 


DOCUMENTATION CONVENTIONS 


1. All commands are terminated by pressing the nonprinting 

RETURN key, causing a carriage return/line feed operation. 
The j symbol is used to represent the RETURN key. 

2. SY: represents the system disk device, which can be a DKs, 
DFs, or DP; disk device. 

3. CTRL/key combinations are typed by holding down the CTRL key 

while typing the required letter key. For example, typing 
CTRL/C ensures that the Monitor will accept the next command 

(but will not necessarily immediately stop a job in 

progress) ? typing CTRL/U deletes all preceding characters on 
a line. Striking CTRL/key characters causes fC to be echoed 
on the operator console. 

4. Information enclosed in brackets ([]) is optional additional 
information. Note, however, that a UIC (User Identification 
Code) , when typed at the console, must actually be delimited 
by left and right brackets. 

5. Braces ({}) are used to enclose items from which a choice 

must be made. 


NOTE 


The software described in this manual 
is furnished to purchaser under a li- 
cense for use on a single computer 
system and can be copied (with inclu- 
sion of DEC's copyright notice) only 
for use in such system, except as may 
otherwise be provided in writing by DEC. 


This document is for information pur- 
poses and is subject to change without 
notice . 


DEC assumes no responsibility for the 
use or reliability of its software on 
equipment which is not supplied by DEC. 
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CHAPTER 1 


INTRODUCTION TO FILCOM 


File Compare (FILCOM) , a system program for use under the DOS/BATCH 
Monitor, allows a user to compare ASCII* source input datasets and 
create a difference output dataset, A dataset is specified as 

dev: filnam. ext [uic] 

where : 

dev: represents a 2-character upper-case alphabetic ASCII device 

code, optionally followed by a unit number when a device 
controller controls multiple units (e.g., DT3) , terminated 
by a colon ( : ) . 

filnam represents a 1- through 6-character upper-case alphabetic or 
numeric ASCII filename. The first character MUST be 
alphabetic. 

.ext represents a 1- through 3-character upper-case alphabetic or 
numeric ASCII filename extension preceded by a period (.). 

[uic] represents a 3-character numeric (octal) ASCII project 
number and a 3-character programmer number, separated by a 
comma (,) and enclosed in brackets ([]). 

If dev: represents a file-structured device (SY:, DP:, DF:, DK:, or 
DT:), a filename (filnam) must be specified. 

If dev: is not specified, the last specified device is used. 

If [uic] is not specified, the current project number and programmer 
number are implied. 

Two sets of option switches allow FILCOM to handle different types of 
comparisons, and help the user select exactly what he wants to 
compare. 

FILCOM can be run when the DOS/BATCH Monitor prints a $ (dollar sign, 
signifying readiness to load a program) by typing 

RUN FILCOM 

at the keyboard. FILCOM then prints a # (number sign) , indicating 
readiness to accept commands. 


*American Standard Code for Information Interchange. 
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NOTE 


Although FILCOM can only be used to compare ASCII 
files, it may be used indirectly to compare binary 
files. The user should first run the FILDMP 
program and dump each binary file onto some 
retrievable medium such as disk, DECtape, or paper 
tape. The ASCII output files generated by FILDMP 
may then be compared using FILCOM. 
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CHAPTER 2 


FILCOM COMMANDS 


FILCOM commands are processed by the DOS/BATCH Command String 
Interpreter (CSI) . This assures a command language consistent with 
other system programs operating under DOS/BATCH. Consult the 
DOS/BATCH Monitor Programmer's Manual for a complete description of 
the CSI. 


2.1 FILCOM COMMAND FORMAT 

Note that FILCOM commands are always typed in response to a # 
character. 

To compare a master file and a newer version of that file, use the 
following command format: 

list dataset< master dataset ,newmas ter dataset ) 

whe re : 

list = specification of the output dataset on which a list of 
dataset the differences between the two files (if any) will be 
written. 

master = the specification of the master dataset, 
dataset 

newmaster - the specification of the newer version of the master 
dataset dataset (or a copy of the master dataset) . 

For example, to compare the files MASTER. OLD and MASTER. NEW, listing 
the differences (if any) on the line printer, the following command is 
used: 


LP:< MASTER. OLD, MASTER. NEW J 


2.2 OPTION SWITCHES 

The two sets of option switches available for use with FILCOM are: 

1. LOCAL switches 

2. GLOBAL switches 


2.2.1 LOCAL Switches 

LOCAL switches enable the user to select the type of comparison he 
wishes to make between the two files. LOCAL switches can be placed 
anywhere in a command string if the correct command format is 
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followed. There can be one or more LOCAL switches in each command 
string. 

EXAMPLES: LP : <FILE. ONE/switch , FILE .TWO ) 

LP: <FILE.OME, FILE. TWO/switch ) 

LP: /switch <FILE. ONE, FILE. TWO ) 

If two switches of the same type are specified in one command string , 
the rightmost switch specification takes precedence. 

The following LOCAL switches are available to the user: 

/SC:n = ASCII source compare for n lines 

/BL:OFF = compare blank lines 

j/BL I = ignore blank lines 
)/BL:ON ( 


/TR ( = compare trailing blanks within lines 
/TR:ON J 

/TR:OFF = ignore trailing blanks within lines 
/MB = reduce multiple blanks to a single blank 

/DE = delete old list file (if it exists) . 


2. 2. 1.1 The SC (Source Compare) Switch 
The format of the SC switch is 
/SC :n 

Where n is a decimal integer specifying the number of consecutive 
lines that constitutes the minimum unit of comparison. A unit of 
comparison in the newmaster file must match a unit of comparison in 
the master file to establish a successful comparison. Since the 
default unit of comparison is a single line, small recurring sets of 
lines that are identical in two dissimilar files will cause a 
successful comparison. Use of this switch will prevent this 
occurrence, and condense the comparison listing. 

EXAMPLES : 

LP : /SC : 3 <FILE . ONE , FILE • TWO ) (three lines must match for a 

successful comparison) 

LP:/SC: 2 <FILE. ONE/SC: 4 , FILE. TWO J (four lines must match for a 

successful comparison) 
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2 .2. 1.2 The BL (Blank Lines) Switch 
The format of the BL switch is 



where /BL : OFF indicates that blank lines are to be included in 
comparisons, and /BL or /BL;ON indicates that blank lines are to be 
ignored during comparisons. Blank lines appear in the difference file 
or listing, and are accounted for in line numbers regardless of the 
setting of the BL switch. 


EXAMPLES s 


LP:/BL:OFF<FILE. ONE, FILE. TWO J 

(include blank 
comparison) 

lines 

during 

LPs/BL<FILE. ONE, FILE. TWO J 

(ignore blank 

comparison) 

lines 

in 

LP:<FILE.ONE/BL:ON, FILE. TWO ) 

(ignore blank 

comparison) 

lines 

in 


If the BL switch is not specified, a default value of /BL:ON is used. 


2 • 2 • 1. 3 The TR (Trailing Blanks) Switch 
The format of the TR switch is 



where /TR or /TR: ON indicate that trailing blanks are significant and 
are to be included in comparisons, and /TRsOFF indicates that trailing 
blanks are to be ignored during comparisons. 


EXAMPLES : 


LP:<FILE. ONE, FILE. TWO/TR ) 

(include trailing 
comparison) 

blanks 

in 

LP:<FILE.ONE/TR;ON, FILE. TWO ) 

(include trailing 
comparison) 

blanks 

in 

LP:/TR:OFF<FILE. ONE, FILE. TWO J 

(ignore trailing 
comparison) 

blanks 

in 


If the TR switch is not specified, a default value of /TR:ON is used. 
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2. 2 ,1.4 The MB (Multiple Blanks) Switch 
The format of the MB switch is 
/MB 

When included in a command string , the MB switch indicates that 
multiple non-trailing blanks within a line are to be regarded as a 
single blanks for comparisons, TAB characters are considered to be 
multiple blanks. If the MB switch is not specified, multiple 
non-trailing blanks are counted separately during comparisons. 


2. 2. 1.5 The DE (Delete Existing) Switch 
The format of the DE switch is 
/DE 

When included in a command string, the DE switch indicates that if a 
specified list dataset exists, it is to be deleted prior to command 
execution. If such a dataset exists and the DE switch is not 
specified, an error results because of the conflict in filenames. 

EXAMPLE : 

DTI : LIST . FIL/DE< FILE . ONE , FILE. TWO ^ if a file named LIST.FIL already 

exists on DECtape 1, delete it 
before attempting to create 
LIST.FIL for this command. 


2.2.2 GLOBAL Switches 

GLOBAL switches are used to specify a default condition for the 
execution of a series of command to follow. They differ from LOCAL 
switches in the following ways: 

1. GLOBAL switches influence a series of commands? LOCAL 

switches influence only the commands in which they occur. 

2. Only one GLOBAL switch is permitted in a command string; 

multiple LOCAL switches are permitted in the same command 

string. 

3. No file comparison can be made in the command string that 

contains a GLOBAL switch? file comparisons can be made in 
command strings containing LOCAL switches. 

An example of the use of a GLOBAL switch is given below: 

< LP : / LS : ON ) 

<FILE. ONE, FILE. TWO J 
<FILE. OLD. FILE. NEW J 
< /LS : OFF,,? 
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As a result of the command strings shown in the above example, 
differences between the files specified in the command strings will be 
listed at the line printer. Command strings following the /LS:OFF 
switch must specify the output device for the difference listing. 

The following GLOBAL switches are available: 

/DF - sets default conditions for one or more LOCAL switches 

/IN - reads and interprets the contents of a specified file as 
FILCOM commands 

/LO - writes a log of all commands executed indirectly through 
use of the /IN switch 

/LS - specifies the output dataset for FILCOM difference listing 


2.2.2. 1 The DF (Define Default) Switch 

The format of the DF switch is: 

( /DF/sw :df (/sw:df . . . ] ) 

< /DF:ON/sw:df [-/sw:df . . . ] / 

( /DF : OFF ) 

where /DF or /DF:ON followed by one or more local switch 
specifications serves to set default conditions for those switches. 
The specification /DF:OFF returns all LOCAL switches to their original 
default conditions (described previously) . 

EXAMPLES : 

/DF: ON/DE :0N J (sets the default condition of the DE 

switch to ON? i.e., until the DF switch 
is turned OFF, list datasets with the 
same name as those specified in a 
command string will be deleted prior to 
execution of the command) 

/DF/DE :ON/TR:OFF J (sets the default condition of the DE 

switch to ON as described above; also 
sets the default condition of the TR 
switch to OFF — trailing blanks will be 
ignored until the DF switch is turned 
OFF) 

/DF: OFF J (returns all previously specified LOCAL 

switches to normal default conditions) 
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2. 2. 2. 2 The IN (Indirect Commands) Switch 

The format of the IN switch is 

dataset/IN 
dataset/IN : ON 
/IN: OFF 

The dataset specified with the IN switch is any legal DOS/BATCH input 
dataset indicating a file whose contents can be read and executed as 
FILCOM commands. 

The last command in the indirect command file can be /IN: OFF 
canceling the IN switch; however/ an enci-of-file condition reached in 
that file also has the effect of turning OFF the IN switch. The 
command /IN:OFF can be issued from the keyboard/ but has no effect 
until FILCOM has completed processing the specified input file? since 
the end-of-file condition will have already turned OFF the IN switch/ 
it is redundant to type /IN: OFF at the keyboard. 

Once the IN switch has been turned ON at the keyboard/ indirect 
command execution will take place after the user presses CTRL/C 
(control-C) and types BEGIN. 

Indirect command files (files specified with the IN switch) can be 
chained/ but care must be taken not to chain a file that chains 
(directly or indirectly) to the current file. 

EXAMPLES : 


DT2 :FILE . IND/IN J 

(causes the contents of FILE. IND on DECtape 2 
to be read and interpreted as FILCOM 
commands ) 


FILE. IND/IN:ON ) 

(causes the contents of FILE. IND on the 
system device to be read and interpreted as 
FILCOM commands 

/IN: OFF J 

(when typed at the keyboard/ has no effect? 
when included in an indirect file r terminates 


indirect interpretation) 



2.2.2. 3 The LO (LOg dataset) Switch 

The format of the LO switch is 

dataset/LO 
dataset/LO:ON 
/LO : OFF 

The LO switch is used to specify a log dataset. Commands specified 
in an indirect command file will be listed in this log when they 
are encountered. Keyboard commands are also listed in this log data- 
set? it is thus redundant to specify the keyboard as the log dataset 
if commands are being entered normally through the keyboard. All list 
file information will also be duplicated in the file specified in the 
log dataset. 
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The command /LO:OFF terminates use of the previously specified log 
dataset; the LO switch can be turned OFF in this manner either at the 
keyboard or within the command coding in an indirect file. 

EXAMPLES : 

< LP : / LO : ON ) (specifies the line printer as a log 

<DT0 : LINES. IND/INj dataset; commands read indirectly from 
<FILE. ONE, FILE. TWO V the file LINES. IND on DECtape unit 0 will be 

listed at the line printer. Also, the files 
FILE. ONE and FILE. TWO on the system device 
will be compared; list output will be 
duplicated at the line printer. 

<DT4 -.LINES. LOG/LO^ (specifies the file LINES.LOG on DECtape 

<LINES . IND/IN^ unit 4 as a log dataset; commands read 

</L0 : OFF^ indirectly from the file LINES. IND on the 

system device will be duplicated in this 
file. List output will also be duplicated in 
this file. After LINES. IND has been read and 
executed, the file LINES.LOG is terminated as 
a log.) 


2. 2. 2. 4 The LS (List dataset) Switch 

The format of the LS switch is 

( dataset/LS ) 

< dataset/LS sON > 

(/LS:OFF ) 

where the commands /LS or /LS:ON specify a default list dataset to be 
used for subsequent commands; this dataset is used until terminated by 
the LS:OFF command. A new default dataset can be specified without 
turning the LS switch OFF, as shown in the example below. 

EXAMPLE s 

<LP:/LS^ . (the line printer is the default list 

<FILE. ONE, FILE. TWOV dataset when comparing the files 

<DT1 : LIST . FILE/LS^) FILE. ONE and FILE. TWO; the file LIST.FIL 

<FILE. SIX, FILE, TEN^) on DECtape unit 1 is the default list 

<FILE. OLD, FILE. NEW J dataset when comparing files FILE. SIX 

</LS:OFF^ and FILE. TEN, and when comparing files 

FILE. OLD and FILE. NEW. The /LS:OFF 
specification terminates the default 
list dataset; subsequent commands must 
contain a list dataset specification 
until the LS switch is turned on again.) 

Table 2-1 contains a summary of all switches usable in the FILCOM 
program. 
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Table 2-1 FILCOM Command Switch Summary 


Switch 

Name 

Type 

Function 

/BL 

Blank Lines 

Local 

When OFF, blank lines are compared in 
files; when ON, blank lines are 
ignored during comparison. 

/DE 

Delete 

Existing 

Local 

When present, existing dataset of 
same name as that specified in command 
is deleted; when not present, deletion 
is not performed. 

/MB 

Multiple 

Blanks 

Local 

When present, reduces multiple blanks 
to a single space during comparison; 
when not present, multiple blanks are 
compared individually. 

/SC 

Source 

Compare 

Local 

Specifies the number of consecutive 
lines to be compared to establish a 
successful comparison . 

/TR 

TRailing 

blanks 

Local 

When ON, trailing blanks are ignored 
during comparison; when OFF, trailing 
blanks are compared. 

/DF 

define 

DeFault 

Global 

Allows user to specify default 
conditions for one or more LOCAL 

switches . 

/IN 

INdirect 

commands 

Global 

Specifies dataset containing file to 
to be read and interpreted as FILCOM 
commands . 

/LO 

LOg dataset 

Global 

Specifies log dataset for subsequent 
commands . 

/LS 

List dataset 

Global 

Specifies list dataset for subsequent 
commands . 
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2.3 OUTPUT FROM FILCOM 


Output from FILCOM consists of the following elements: 

1. A copy of the FILCOM command that initiated the compare, 

2. For the master copy, the line number of the difference 

detected followed by the associated text, 

3. For the new master, the line number of the difference 

detected followed by the associated text. 

Figure 2-1 illustrates sample output from FILCOM generated by 
comparing two versions of the Gettysburg Address. 


4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 * -4- 4 4 4- 4- 4 4 4 4 4 4 4 4 4 4 4 4 4 4 
4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 44 4 4: 4 4 4 4 4 4 

KB: < D T 6 ; F I L C 0 1 . F i L , D T 6 : F I L I! 0 2. FIL 

4 * 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 ! 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 I 1 4 4 
4 4 4 4 4 4 4 4 4 4 4 * 4 4 4 4 4 4 4 4 4 4 4' 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 

MASTER LINE 60002 

THIS CONTINENT ft NEK NftTION CONCEIVED IN LIBERTY RND DEDICATED TO 
THE PROPOSITION f H f? T RLL MEN RRE CRERTED E Q U ft L . 


4 tft 4 4 4 


NEW MRS TER LINE 00062 

THIS CONTINENT AM 0.0 NOT JON CONCEIVED IN LIBERTY A N D PEP I CRT ED TO 
THE PROPOSITION T HRT RLL MEN ft RE CREATED EC! URL 

4 f: 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 


Figure 2-1. Sample FILCOM Output 




CHAPTER 3 


ERROR MESSAGES 

The FILCOM program issues three types of error messages to identify 
the source of errors during execution: 

1. Command Syntax Errors 

2. I/O Device Initialization Errors and I/O Errors 

3 . Runtime Errors 

3.1 COMMAND SYNTAX ERRORS 

Table 3-1 lists command syntax error messages and their meanings. 


Table 3-1 Command Syntax Errors 


Message 

TOO MANY GLOBAL SWITCHES 


UNKNOWN OPTION 


BAD NUMERIC FIELD 


SYNTAX ERROR IN COMMAND 


TOO MANY SWITCHES 


WRONG # OF INPUT DEVICES 


Meaning 

More than one GLOBAL switch has been 
specified in a command string. The 
command must be retyped with only one 
GLOBAL switch per string. 

FILCOM does not recognize a switch name 
in a command string? possible mistyping 
of switch. Command must be retyped 
using correct switch designation. 

An invalid number has been typed as the 
argument of a switch (e.g., the SC 
switch) . Command must be retyped using 
valid number for the switch. 

A typed command does not conform to 
rules of the CSI; command must be 
retyped to conform to CSI rules. 

The number of switches in a command 
exceeds the capacity of the switch 
buffer. Commands must be retyped using 
fewer switches per string. 

A command has been entered containing 
more (or less) than two input dataset 
specifications. Two input datasets 
(master and newmaster) must be specified 
for a comparison. Command must be 
retyped correctly. 
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3.2 I/O DEVICE INITIALIZATION ERRORS AND I/O ERRORS 
The following message formats indicate an I/O errors 

xxxx DEVICE I NIT ERROR 
xxxx DEVICE OPEN ERROR 
xxxx 10 ERROR 

where xxxx indicates a file in error, and can be MASTER, NEWMAS , LIST, 
or COMMAND (indirect command file) . These messages are issued if one 
or more of the following conditions exists 

1. An attempt is made to initialize a nonexistent device 

2 . Output is attempted to an input-only device 

3 . Input is attempted from an output-only device 

4. An output device (list or log dataset) is duplicated in two 
commands. 

3.3 RUNTIME ERRORS 

Table 3-2 lists runtime error messages and their meanings. 


Message Meaning 

COMPARE CAPACITY EXCEEDED There is not enough core available to 

compare two specified files. 

RAN OUT OF BUFFER HEADERS Program error in FILCOM. Kill program 

and re-run. If error message is issued 
again, report via SPR. * 


* Software Performance Report? submit to Digital Equipment 
Corporation, Software Information Services, Maynard, Massachusetts 
01754 . 
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HOW TO OBTAIN SOFTWARE INFORMATION 


Announcements for new and revised software , as well as programming 
notes, software problems , and documentation corrections , are published 
by Software Information Service in the following newsletters. 

DIGITAL Software News for the PDP-8 and PDP-12 
DIGITAL Software News for the PDP-11 
DIGITAL Software News for 18-bit Computers 

These newsletters contain information applicable to software available 
from DIGITAL'S Software Distribution Center. Articles in DIGITAL 
Software News update the cumulative Software Performance Summary which 
is included in each basic kit of system software for new computers. 
To assure that the monthly DIGITAL Software News is sent to the 
appropriate software contact at your installation, please check with 
the Software Specialist or Sales Engineer at your nearest DIGITAL 
office. 

Questions or problems concerning DIGITAL'S software should be reported 
to the Software Specialist. If no Software Specialist is available, 
please send a Software Performance Report form with details of the 
problems to: 

Digital Equipment Corporation 
Software Information Service 
Software Engineering and Services 
Maynard, Massachusetts 01754 

These forms, which are provided in the software kit, should be fully 
completed and accompanied by terminal output as well as listings or 
tapes of the user program to facilitate a complete investigation. An 
answer will be sent to the individual, and appropriate topics of 
general interest will be printed in the newsletter. 

Orders for new and revised software manuals, additional Software 
Performance Report forms, and software price lists should be directed 
to the nearest DIGITAL field office or representative. USA customers 
may order directly from the Software Distribution Center in Maynard. 
When ordering, include the code number and a brief description of the 
software requested. 

Digital Equipment Computer Users Society (DECUS) maintains a user 
library and publishes a catalog of programs as well as the DECUSCOPE 
magazine for its members and non-members who request it. For further 
information, please write to: 

Digital Equipment Corporation 
DECUS 

Software Engineering and Services 
Maynard, Massachusetts 01754 
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